Return guide and manifest to original format, but with additional info

This puts the main "Project Layout" section back into `manifest.md` as it was
before, but adds a bit more detail to that section both those pages and a link
between them.

diff --git a/src/doc/guide.md b/src/doc/guide.md
index 9e9f5cc55a5234f61ccec9426d16e24494a8b02f..b3743a64b6161aa7774af796f99d18edfc82e16c 100644 (file)
--- a/src/doc/guide.md
+++ b/src/doc/guide.md
@@ -202,43 +202,19 @@ we choose to `cargo update` again.
 # Project Layout
 
 Cargo uses conventions for file placement to make it easy to dive into a new
-Cargo project. 
+Cargo project. Here the conventions that Cargo uses:
 
-`Cargo.toml` is kept in the root directory, as is `Cargo.lock`.
+* `Cargo.toml` and `Cargo.lock` are stored in the root of your project.
+* Source code goes in the `src` directory.
+* The default library file is `src/lib.rs`.
+* The default executable file is `src/main.rs`.
+* Other executables can be placed in `src/bin/*.rs`.
+* External tests go in the `tests` directory.
+* Example executable files go in the `examples` directory.
+* Benchmarks go in the `examples` directory.
 
-If your project is an executable, name the main source file `src/main.rs`. If it
-is a library, name the main source file `src/lib.rs`. Cargo can create either of
-these automatically with `cargo new --bin` or `cargo new`.
-
-## Optional Components
-
- * `src/bin/`: Other executables, to be built by default with 
-    `cargo build`
- * `examples/`: Examples of usage, built with `cargo test` or `cargo build 
-    --example NAME`
- * `tests/`: Integration tests, built and run with `cargo test`
- * `benches/`: Benchmarks, built and run with `cargo bench`
- 
 These are explained in more detail in the [manifest
-description](manifest.html#examples), but for now, here is an example directory
-layout:
-
-```notrust
-Cargo.toml
-Cargo.lock
-▾ src/          # directory containing source files
-  lib.rs        # the main entry point for libraries and packages
-  main.rs       # the default file for a project producing an executable
-  *.rs          # other modules
-  ▾ bin/        # (optional) directory containing executables
-    *.rs
-▾ examples/     # (optional) examples of library usage
-  *.rs
-▾ tests/        # (optional) integration tests
-  *.rs
-▾ benches/      # (optional) benchmarks
-  *.rs
-```
+description](manifest.html#the-project-layout).
 
 # Cargo.toml vs Cargo.lock
 

diff --git a/src/doc/manifest.md b/src/doc/manifest.md
index 4f37468000291e97086799e72fa36c5f0b2f40e4..f948991c7ae9036a125dc6606ccbb0d740fc8577 100644 (file)
--- a/src/doc/manifest.md
+++ b/src/doc/manifest.md
@@ -365,16 +365,41 @@ tests and benchmarks.
 These dependencies are *not* propagated to other packages which depend on this
 package.
 
+# The Project Layout
+
+If your project is an executable, name the main source file `src/main.rs`.
+If it is a library, name the main source file `src/lib.rs`.
+
+Cargo will also treat any files located in `src/bin/*.rs` as
+executables.
+
+Your project can optionally contain folders named `examples`, `tests`, and
+`benches`, which Cargo will treat as containing example executable files,
+integration tests, and benchmarks respectively.
+
+```notrust
+▾ src/          # directory containing source files
+  lib.rs        # the main entry point for libraries and packages
+  main.rs       # the main entry point for projects producing executables
+  ▾ bin/        # (optional) directory containing additional executables
+    *.rs
+▾ examples/     # (optional) examples
+  *.rs
+▾ tests/        # (optional) integration tests
+  *.rs
+▾ benches/      # (optional) benchmarks
+  *.rs
+```
+
 # Examples
 
-Files located under `examples` are example uses of the functionality provided by
-the library (see [the guide](guide.html#project-layout) for a further
-description of standard project layout).  When compiled, they are placed in the
+Files located under `examples` are example uses of the functionality
+provided by the library. When compiled, they are placed in the
 `target/examples` directory.
 
-They must compile as executables (with `main.rs`) and load in the
-library by using `extern crate <library-name>`. They are compiled when
-you run your tests to protect them from bitrotting.
+They must compile as executables (with a `main()` function) and load in the
+library by using `extern crate <library-name>`. They are compiled when you run
+your tests to protect them from bitrotting.
 
 # Tests